.TH stoker_mysql 5 "14 November 2008" "version 0.91" "Stoker Manual"
.SH NAME
stoker_mysql \- Stoker MySQL machine source
.SH DESCRIPTION
Stoker can obtain target machine and group information from a MySQL server.
To use MySQL, the host running stoker(8) must have the MySQLdb package
(http://mysql-python.sourceforge.net) installed.
This package is only a dependency of Stoker if MySQL is enabled in
stoker.conf(5).
.SH MYSQL SERVER REQUIREMENTS
A working MySQL server, with tables that can be queried for both machine
and group information, must be available.
Since MySQL requires authentication, an unprivileged (read-only) user
account with a simple password should be created.
This password must be stored in plaintext in stoker.conf(5), so the
account permissions should be secure for untrusted access.
.SH SPECIAL CONSIDERATIONS
This MySQL machine source was designed to work with ROCKS.
As a result, targets that consist exclusively of digits (numbers) are
treated as rack numbers, or Stoker groups.
All other targets are assumed to be machine names.
.SH CONFIGURATION DIRECTIVES
The following stoker.conf(5) directives configure Stoker to use a MySQL server
as a machine source:
.TP
.B use_mysql = <true | false>
Enables or disables the MySQL machine source.
.TP
.B mysql_host = <host>
Specifies the host on which the MySQL server lives.
.TP
.B mysql_db = <db>
Specifies the name of the MySQL database to use on the server.
.TP
.B mysql_user = <user>
Specifies the username with which to bind to the MySQL server.
.TP
.B mysql_cred = <password>
Specifies the password with which to bind to the MySQL server.
.TP
.B mysql_machine_query = <query>
Query to use when retrieving the list of machines from the server.
.TP
.B mysql_group_query = <query>
Query to use when retrieving the list of groups from the server.
.TP
.B mysql_resolve_hosts_query = <query>
Query to use when resolving machine names.
The special keyword \fB%targets\fR will be replaced with a list of the
machine names to query (comma-separated), suitable for use in a WHERE clause.
.TP
.B mysql_resolve_groups_query = <query>
Query to use when resolving group (rack) numbers.
The special keyword \fB%targets\fR will be replaced with a list of the
rack numbers to query (comma-separated), suitable for use in a WHERE clause.
.SH DEFAULT SETTINGS
If unspecified, the MySQL resolver settings default to those suitable for
use with ROCKS.
The default host will be 127.0.0.1, with database name "cluster", logging
into the database using the "root" username and "p12345" password, with
queries suitable for ROCKS.
.SH EXAMPLES
A simple set of configuration directives to connect to a ROCKS MySQL server
on the same host, using an unprivileged account (strongly recommended).

.nf
use_mysql = true
mysql_user = user
mysql_cred = 123456
.fi

.SH SEE ALSO
stoker.conf(5), scf2(5), stoker(8)
.SH AUTHOR
Mike Murphy <mamurph@cs.clemson.edu>
.SH DISCLAIMER
This material is based upon work supported under a National Science
Foundation Graduate Research Fellowship.
Any opinions, findings, conclusions or recommendations expressed in this
publication are those of the author(s) and do not necessarily reflect the
views of the National Science Foundation.
